Contributing to Magento 2

Opening Up

Magento 2 Engineering Lead Max Yekaterynenko announced last week that the we would soon accept public pull requests on the Magento 2 GitHub repository. I’m delighted to share that the first pull requests have been now been merged! Tobias Zander has the honor of being the first community member with a merged pull request (PR) – one which cleans up a funny copy-paste error. I also had a PR merged to correct a misspelling of a certain name in the core code. While these first two merged PRs offer purely cosmetic improvements (and allowed us a final test of the new contribution model), they represent a new, exciting reality for Magento development: the community now has the ability to contribute directly to the Magento 2 codebase, and this collaboration takes place in full view of everyone – just as one would expect of an open source software.

How does it work?

Contributions to the Magento 2 codebase are done via GitHub using the fork & pull model. This contribution model has contributors maintaining their own copy of the forked codebase (which can easily be synced with the main copy). The forked repository is then used to submit a request to the base repository to “pull” a set of changes (hence the phrase “pull request”). The excellent GitHub interface has a GUI for doing all of this and even includes a discussion panel for each PR which allows everyone to see the reason why a PR is or is not merged as well as the ability to add to the discussion. GitHub also has a very good primer on pull requests under their help site.

Contributing to Magento 2 on GitHub

As mentioned, there are two essential actions in order to submit a contribution. First, fork the magento/magento2 repository under your own free GitHub account (or collaborate with someone else who has done this). Once you have a forked repository to use, you can create PRs based on changes made to that fork.

Forking a repository on GitHub is easy:

Create or log in to your free account on GitHub
Navigate to the Magento 2 repository on GitHub
Click the “Fork” button at the top right:
Clone the repo into your development environment, get the app installed, and start playing!

Creating a pull request is also easy:

First, check the existing PRs and make sure you aren’t duplicating others’ work!
Create a feature branch for your changes and push those changes to the copy of your repository at GitHub (this is the best way to organize and even update your PR)
In your repository, click the pull request icon at the right, and then click the green “New Pull Request” button:
Ensure that the “base” (the left side) is set to magento:develop and the “head” (the right side) is set to the appropriate branch/commit/etc.:
Review the changes, then click the green “Create pull request” button, fill out the form, and click the “Create pull request” button again to submit the PR – that’s it!

As a reminder: remember to make your magento/magento2 pull request to the “develop” branch. I forgot to do this with my first PR and now I can never visit Kiev ;-)!

After submitting your PR you can head over to the magento/magento2 repository’s Pull Requests panel to see you PR along with the others. Your PR will undergo automated testing, and assuming it passes, will be up for consideration by the core team for inclusion in the Magento 2 core.

Additional notes about contributions:

Contributions must adhere to Magento coding standards
PRs must be accompanied by a description of their purpose
PRs which include new logic or new features must be submitted along with unit/integration test coverage (we will be releasing more information on writing test coverage in the near future)
For large features or changes, please open an issue here and discuss first. This may prevent duplicate or unnecessary effort, and it may gain you some additional contributors.
PRs which include new features must be submitted along with a proposed documentation update as well (see below)

Contributions to documentation

Magento 2 documentation is also available for update on GitHub via the same fork & pull model. In fact, it’s easy to create and propose changes or additions to the documentation by using GitHub’s built-in editor – no need to download the forked repository to work on it. For more information, see my buddy Bradburn Young’s recent guest post on Alan Kent’s blog. The big thing: make pull requests to the develop branch, just like you would for the Magento 2 codebase.

A note about Magento 2 development environments

If you’ve been a Magento developer for a little while, please note that there are a number of architectural and environmental differences between Magento 2 and Magento 1.x – including higher minimum versions for PHP and MySQL – which may require a new development environment configuration in order to work with Magento 2. If you need to continue supporting an incompatible development environment for current / legacy projects, virtualization is a popular, maintainable, and increasingly simple option to have a separate execution environment for Magento 2. There are several resources which have information to get you up and running with virtualization:

Alan Kent‘s article, “Reducing Magento 2 Install Pain Through Virtualization”
Ryan Street‘s ryanstreet/magento2-vagrant repo at GitHub
Rolando Granadino‘s rgranadino/mage2_vagrant repo at GitHub

I will certainly add to this list as time goes on; feel free to comment with links to other resources which you find helpful – and let me know about any resources which are less than helpful as well so we can work with the authors to get them corrected.

We’ve been working hard to get Magento 2 ready for contribution, and there has been a lot of excitement internally to see this become a reality. Now it is up to the community to make the most of our open source contribution model. The Magento 2 Developer Beta closes in a few short months, and Q4 of 2015 will be here before we know it as well. Everyone’s involvement along the way is critical to making sure that Magento 2 is the best successor to Magento 1.x, one which will serve us well in the years to come. Onward and upward!